NAME¶

nbdkit-vddk-plugin - nbdkit VMware VDDK plugin

SYNOPSIS¶

 nbdkit vddk file=FILENAME [config=FILENAME] [libdir=LIBRARY]
             [vm=moref=ID] [server=HOSTNAME] [user=USERNAME]
             [password=PASSWORD | password=- | password=+FILENAME]
             [cookie=COOKIE] [thumbprint=THUMBPRINT]
             [port=PORT] [nfchostport=PORT]
             [snapshot=MOREF] [transports=MODE:MODE:...]
 nbdkit vddk --dump-plugin

DESCRIPTION¶

"nbdkit-vddk-plugin" is an nbdkit(1) plugin that serves files from local VMware VMDK files, VMware ESXi servers, VMware VCenter servers, and other sources. It requires VMware's proprietary VDDK library that you must download yourself separately.

The plugin can serve read-only (if the -r option is used) or read/write.

LIBRARY AND CONFIG FILE LOCATIONS¶

If the VDDK library (libvixDiskLib.so.6) is located on a non-standard path, you may need to set "LD_LIBRARY_PATH" or modify /etc/ld.so.conf before this plugin will work. In addition you may want to set the "libdir" parameter so that the VDDK library can load plugins like Advanced Transport.

For 64 bit platforms pass the lib64 subdirectory:

 export LD_LIBRARY_PATH=/path/to/vmware-vix-disklib-distrib/lib64

For 32 bit platforms pass the lib32 subdirectory:

 export LD_LIBRARY_PATH=/path/to/vmware-vix-disklib-distrib/lib32

Then pass the VDDK distribution directory as "libdir" along with other parameters as required:

 nbdkit vddk \
     libdir=/path/to/vmware-vix-disklib-distrib \
     file=file.vmdk

VDDK itself looks in a few default locations for the optional configuration file, usually including /etc/vmware/config and $HOME/.vmware/config, but you can override this using the "config" parameter.

PARAMETERS¶

config=FILENAME

Optional. The name of the VDDK configuration file.

cookie=COOKIE

Optional. Cookie from existing authenticated session on the host.

file=FILENAME

Required. Set the name of the VMDK file to serve.

For local files you must supply an absolute path.

For remote files this is usually a path on the VMware server with the format "[datastore] path/to/file.vmdk". You can find the path using virsh(1). For ESXi:

 virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
    

For vCenter:

 virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
       dumpxml guestname
    

If a VM has multiple disks, nbdkit can only serve one at a time. To serve more than one you must run multiple copies of nbdkit. (See "NOTES" below).

libdir=PATHNAME

Optional. This sets the path of the VMware VDDK distribution.

VDDK uses this to load its own plugins, if this path is unspecified or wrong then VDDK will work with reduced functionality.

If the parameter is not given, then a hard-coded path determined at compile time is used, see "DUMP-PLUGIN OUTPUT" below.

nfchostport=PORT

Optional. Port used to establish an NFC connection to ESXi. Defaults to 902.

(Only supported in VDDK ≥ 5.5.5 and ≥ 6.0.1)

password=PASSWORD

Optional (required for remote connections). Set the password to use when connecting to the remote server.

Note that passing this on the command line is not secure on shared machines.

password=-

Optional (required for remote connections). Ask for the password (interactively) when nbdkit starts up.

password=+FILENAME

Optional (required for remote connections). Read the password from the named file. This is the most secure method to supply a password, as long as you set the permissions on the file appropriately.

port=PORT

Optional. The port on the VCenter/ESXi host. Defaults to 443.

server=HOSTNAME

Optional (required for remote connections). The hostname or IP address of VCenter or ESXi host.

snapshot=MOREF

Optional. The Managed Object Reference of the snapshot.

thumbprint=THUMBPRINT

Optional. The SSL (SHA1) thumbprint for validating the SSL certificate.

The format is "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx" (20 hex digit pairs).

To extract this, log in to the ESXi hypervisor shell and run this command:

 # openssl x509 -in /etc/vmware/ssl/rui.crt -fingerprint -sha1 -noout
    

For VMware vCenter servers the thumbprint is printed on the text console of the server or is available by logging in to the server and using this command:

 # openssl x509 -in /etc/vmware-vpx/ssl/rui.crt -fingerprint -sha1 -noout
    

transports=MODE:MODE:...

Optional. List of one or more transport modes to use. Possible values include ‘nbd’, ‘nbdssl’, ‘san’, ‘hotadd’, ‘file’ (there may be others). If not given, VDDK will try to choose the best transport mode.

user=USERNAME

Optional (required for remote connections). The username to connect to the remote server as.

vm=moref=ID

Optional (required for remote connections). The Managed Object Reference ("moref") of the virtual machine.

For VMware ESXi hypervisors, this is a number (eg. "vm=moref=2"). For VMware VCenter, this is a string beginning with "vm-") (eg. "vm=moref=vm-16"). Across ESXi and vCenter the numbers are different even for the same virtual machine.

If you have libvirt ≥ 3.7, the moref is available in the virsh(1) "dumpxml" output:

 $ virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
 ...
 <vmware:moref>2</vmware:moref>
 ...
    

or:

 $ virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
       dumpxml guestname
 ...
 <vmware:moref>vm-16</vmware:moref>
 ...
    

An alternative way to find the moref of a VM is using the "moRefFinder.pl" script written by William Lam (http://www.virtuallyghetto.com/2011/11/vsphere-moref-managed-object-reference.html https://blogs.vmware.com/vsphere/2012/02/uniquely-identifying-virtual-machines-in-vsphere-and-vcloud-part-2-technical.html).

vimapiver=APIVER

This parameter is ignored for backwards compatibility.

EXAMPLES¶

 nbdkit vddk file=/absolute/path/to/file.vmdk

 nbdkit vddk user=root password=+/tmp/rootpw \
             server=esxi.example.com thumbprint=xx:xx:xx:... \
             vm=moref=2 \
             file="[datastore1] Fedora/Fedora.vmdk"

 nbdkit vddk user=root password=vmware \
             server=vcenter.example.com thumbprint=xx:xx:xx:... \
             vm=moref=vm-16 \
             file="[datastore1] Fedora/Fedora.vmdk"

DUMP-PLUGIN OUTPUT¶

To query more information about the plugin (and whether it is working), use:

 nbdkit vddk --dump-plugin

If the plugin is not present, not working or the library path is wrong you will get an error.

If it works the output will include:

"vddk_default_libdir=..."

The compiled-in library path. Use "libdir=PATHNAME" to override this at runtime.

"vddk_has_nfchostport=1"

If this is printed then the "nfchostport=PORT" parameter is supported by this build.

"vddk_dll=..."

Prints the full path to the VDDK shared library. Since this requires a glibc extension it may not be available in all builds of the plugin.

DEBUGGING VDDK¶

Debugging messages can be very helpful if you have problems connecting to VMware servers, or to find the list of available transport modes, or to diagnose SAN problems.

Run nbdkit like this to see all debugging messages:

 nbdkit -f -v vddk file=FILENAME [...]

NOTES¶

 nbdkit: vddk[3]: error: [NFC ERROR] NfcFssrvrProcessErrorMsg:
 received NFC error 5 from server: Failed to allocate the
 requested 2097176 bytes

 <nfcsvc>
   <path>libnfcsvc.so</path>
   <enabled>true</enabled>
   <maxMemory>50331648</maxMemory>
   <maxStreamMemory>10485760</maxStreamMemory>
 </nfcsvc>

 # /etc/init.d/hostd restart

SEE ALSO¶

nbdkit(1), nbdkit-plugin(3), virsh(1), https://www.vmware.com/support/developer/vddk/

AUTHORS¶

Richard W.M. Jones

COPYRIGHT¶

Copyright (C) 2013-2018 Red Hat Inc.

LICENSE¶

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of Red Hat nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.